ResCompare can create a self╨applying patch application. That╒s a tiny application that can change an old version of a file into a newer version. You can use the patch to distribute upgrades of your software without sending a new copy of the entire application. Patches contain only the differences between versions, and are typically 40% of the original file, so you can save disk space and communications upload/download time by sending the patch instead of the entire application. Also, the patch is only useful to owners of the original version, so you can distribute patches to your commercial software over public bulletin boards.
How to Apply a Patch
Patches are easy to apply. Just open a self╨applying patch and it displays some notes.
╩
It then prompts you for the file to patch. Depending on how it was configured, the patch may also ask you where to save the new version.
╩
A bar graph displays the progress.
╩
When done, it tells you if it was successful.
╩
It╒s that simple╤a true no╨brainer.
Creating Self╨Applying Patches
Self╨applying patches are created with ResCompare╒s Make Patch command. After comparing the old file to the new file, select the resources that you want included in the patch and choose Make Patch from the Change menu.
Note that you needn╒t patch all the changed resources. Perhaps your application writes personalization data into itself; ResCompare lets you choose not to update those resources, by selecting only the ones you want the patch to change.
ResCompare asks if you want to create a new patch or append to an existing patch.
╩
If you╒re making a new patch, click New. A second dialog lets you set various patch options.
╩
Ñ You can choose the prompt that the patch will use when asking for the original file. By default, the prompt will be ╥Where is <original-file>?╙, where the name of your master file is used for <original-file>.
Ñ You have several choices for the dispositions of the master (original) file and the update (patched) file. That is, what the patch should do with these files after patching. Some combinations of options are not allowed because they are nonsensical.
With certain master file dispositions, you have the option of renaming the master file as it is moved about. You can provide a template file name to which the patch will attempt to rename the master file. Within the template, the substitution strings ^FILE and ^VERS will be changed by the patch to the chosen file╒s actual name and version, respectively.
The following table outlines the various choices, and under what circumstances you might need to use them.
Master Update Effect
Leave Save as Master file left as-is; user prompted to save update file.
Safest choice, and thus the default. However, if the user chooses
to replace the master file, the dispositions change to
╥Master: Delete; Update: Replace╙, which is the least safe choice.
But that╒s OK, because the user confirmed the ╥replace existing?╙
alert.
LeaveRename Save as Master file renamed; user prompted to save update file.
Leave Exchange Illegal; you can╒t leave the master file alone and exchange it
with the update file.
LeaveRename Exchange Master and update files exchanged; master file moved and
renamed.
A good way to update an open file, but only if the file╒s location
is not significant. Using this for an extension in the Extensions
folder would not be a good idea, as it would leave the renamed
master file in the Extensions folder.
Leave Replace Illegal; you can╒t leave the master file alone and replace it.
LeaveRename Replace Master file moved and renamed; update file moved and
renamed to master location from temporary items folder.
Delete Save as Master file deleted; user prompted to save update file.
Delete Exchange Master and update files exchanged; master file deleted.
Delete Replace Master file deleted; update file moved and renamed to
master location from temporary items folder.
These three are the least safe choices, in my opinion.
Ñ The box labeled ╥Smart-Installed Application╙ should normally be left unchecked. However, if you are creating a patch for an application that can be installed by the user as either a 68K-only, PPC-only, or ╥fat╙ variant of itself, you should check this box. When checked, ResCompare automatically sets a flag on each resource from a select group that may or may not be present in each of the three variants. The flag (needNotVerify, see the document ╥Patch File Format╙) tells the patch to only apply its updates in the presence of the resource, and not to complain if the resource doesn╒t exist.
When you click OK, ResCompare asks you to save the patch.
╩
Here, you may choose the language that the user interface of the patch application should use. Currently, the following languages are available.
Ñ German (courtesy of Frank Nieºen)
Ñ Italian (courtesy of Dario Accornero)
Ñ Swedish (courtesy of RenÄ Hedemyr)
Ñ Danish (courtesy of J┐rgen M╛llinger)
Ñ Japanese (courtesy of Masatsugu Nagata)
Ñ Russian (courtesy of Slava Karpenko)
These translations were contributed by the persons noted above, and more are becoming available all the time. If you would like to translate a patch to another language, see the section ╥Translating Patch for a Foreign Language,╙ below, for instructions.
ResCompare then finds the differences between the selected resources and saves them in the self╨applying patch.
One Patch for Many Versions
If you have released several versions of your application, you can create a patch that will work with all released versions. This is done by appending additional patches to an existing one. I╒ll go through an example that describes the process. Let╒s say you have three released versions of your application named Sample: version 1.0, version 1.0.1 and version 1.2. You want to release version 1.3 as a self╨applying patch that will upgrade all existing versions.
Ñ Create the new patch ╥Sample 1.3 patch,╙ as described above, that patches version 1.0 to 1.0.1.
Ñ Using ResCompare, compare version 1.0.1 to version 1.2. Select the changed resources and choose Make Patch. When asked if you want to create a new patch, click the Append button and select ╥Sample 1.3 patch,╙ which you created in step 1. After opening the patch, you will have an opportunity to adjust the patch options.
Ñ Repeat step 2 for the changes from version 1.2 to 1.3. You now have a self╨applying patch that can upgrade versions 1.0, 1.0.1 and 1.2 of Sample to version 1.3.
An easy way to do this incrementally is:
Ñ Create a new patch for the first upgrade (1.0 => 1.0.1).
Ñ When the time comes to release the second upgrade, duplicate the patch for the first upgrade, rename it, and append the new patch information to it (1.0.1 => 1.2).
Ñ For each subsequent upgrade, always duplicate and rename the last patch you created, and append your changes to it.
One Patch for Many Files
A single patch can also contain the information needed to patch multiple files; for example, an application and its Apple Guide file. Simply compare each additional file and append the patch information, as describe above. The patch options can be set individually for each file you want patched.
Adding Notes to the Patch
Open the patch with a resource editor and edit 'TEXT'/'styl' resource 128. This resource contains the patch notes that are displayed when the patch is first opened. You may add any notes here that you like, but at the very least, please add your contact information (phone number, e-mail address, etc.). You would not believe the amount of e-mail I get from people who have questions about some patch that I didn╒t make!
Also, if you delete 'TEXT'/'styl' 128, the patch will skip the initial patch info dialog completely and move on to prompting the user for the target file.
Translating Patch To A Foreign Language
To make your own localized patch, follow these steps.
I. TRANSLATION
Ñ Build a small patch. Use ╥English (US)╙ for the language.
Ñ Duplicate it. Give the duplicate the US English name of your language (ie: ╥Japanese╙).
Ñ Translate the copy. Be sure to set the region code on the 'vers' 1 resource to match your language, and to add ╥<your language> translation by <your name>.╙ to the end of the long string (ie: ╥Japanese translation by Masatsugu Nagata.╙). Of course, you can translate that last sentence.
Ñ Run the localized patch. Make sure everything works and appears ok.
II. ENCAPSULATION
Ñ Compare the localized patch to the original. (Hint: You can use ResCompare to do this. :-)
Ñ Open the localized patch in ResEdit. Delete all resources that are not in ResCompare╒s list of differences. In particular, there should be no resources of type BNDL/CNTL/CODE/CREL/DATA/DREL/ICN# (etc.)/SIZE/ZVER/ZAP#/ZIL#/ZIS#/ZAP .
Ñ In ResCompare, choose ╥File: Encapsulate.╙ Check ╥Resource fork only.╙ Open your localized patch.
Ñ Save the encapsulation. Name it ╥[<your language>].rsrc╙ (ie: ╥[Japanese].rsrc╙). This should be the default.
III. INSTALLATION
Ñ Open the encapsulation in ResEdit. There should be only a single 'RF ' resource with and ID of 1000 + your region code. Its name should be your language (ie: 'RF ' 1014, name=╥Japanese╙).
Ñ Open ResCompare in ResEdit. You may want to make a backup of ResCompare first. Copy the new 'RF╩╩' resource into it. Save.
IV. SUBMISSION
Ñ Send the encapsulation file to me. My address is hecht@vnet.net. Receive fame, fortune, and my undying gratitude. That╒s it!
Limitations
When making patches, ResCompare is highly dependent on the version numbers stored in the 'vers' 1 resource. If your application doesn╒t have a 'vers' 1 resource, or if it contains the same version number in both the master and update files, or if it is otherwise malformed, spindled, or mutilated, ResCompare will warn you about it. However, ResCompare does allow you to create and append patches whose version numbers are not in strict ascending order. But, it is up to you to test such patches thoroughly, on all intended versions of your application, since this disables version checking.
Self╨applying patches work on applications the same way that some viruses do (by modifying their 'CODE' resources). Because of this, some virus detectors may get upset when a patch starts doing its thing. Tell your users (in the patch notes, perhaps) to turn off virus protectors and restart before patching. Because of this limitation, please remember to check your floppies for viruses before distributing a patch on them.
The self╨applying patch requires some free space on the volume, and it makes every possible attempt to apply the patch within the space provided. However, I have had some reports of problems patching files on a nearly full floppy. I therefore suggest copying the file to your hard disk before patching.
ResCompare sets the patch╒s preferred memory partition to be large enough to accommodate the largest patch data it will encounter. However, be sure to test the patch in a low memory situation, and increase the preferred size if necessary.
The ╥Smart-Installed Application╙ feature works quite well, except for one caveat. If your patch adds new resources that are not meant for all variants of your application, those resources get added to all variants of your application anyway. The prototypical example is, you add a new 'CODE' resource, and the patch puts it into your PPC-only variant. Other than the increase in application size, this is usually harmless. Oh well.
To contact me
I hope you enjoy ResCompare. If you like it and find it useful, let me hear from you. If you have any suggestions, questions, or bug reports, send me e╨mail at hecht@vnet.net.
